Result Notifications
While you are setting up your remote data store definitions, you will have to consider how Orbital communicates with the remote data store and how the results of a query or script are sent to the remote data store.
Orbital Result Notification Structures
| Note: | Orbital can asynchronously send results to a Remote Data Store (RDS) configured through the UI or via API. |
The first option is the Cisco Threat Response Private Intelligence store (available via Cisco XDR only), which is described here and can be viewed here.
The remaining options all share a similar format described in this topic. With both a compact and expanded table-oriented result format that can be sent to any personal RDS, Orbital also supports sending results to Amazon S3™, Azure™, and Splunk™;. In all cases successfully creating an RDS requires making sure the destination exists, can be authenticated to with the credentials provided, and successfully written to. Each time an RDS is created or selected in a new scheduled query Orbital sends a ping to the RDS, which is a small packet that must be successfully delivered for the request to succeed.
Ping Requsts
When using an Amazon S3 RDS the ping is stored as a file named orbital-rds-ping.json and is overwritten with each request. This ping file can be safely discarded. The format of a ping is defined in the sections below.
| Note: | All times are UTC, in RFC3339 format. |
Ping Headers
|
{ "X-Orbital-Event": ["ping"], "X-Orbital-Eventid": ["e7fc42a9-97d5-5ea5-f1d9-dd6dae62f150"], // Example internal Request ID, useful for support. "Accept-Encoding": ["gzip"], "User-Agent": ["Go-http-client/1.1"], "Content-Type": ["application/json"] } |
Default Ping Body
|
{ "ping": { "id": "3JWq5ZWB8jFEnry0NoA3Lg", "created": "2019-09-26T15:46:38.717497401Z", "creator": "7ef6da70-eeef-4a18-83ea-2e94dd6f9ba2", "disabled": false, "organization": "d76c035d-e896-438c-8d75-158be85fc958", "updated": "2019-09-26T15:46:38.717497401Z", "lastcalled": "0001-01-01T00:00:00Z", "laststatus": "", "errormessage": "", "config": { "label": "MyHost RDS", "url": "http://myhost.com/rds" } } } |
// Example ID of new RDS object, or blank for a live postback request. // Time the RDS was created. // Example user ID that created the RDS. // Current "disabled" state for the RDS. // Example organization ID of the user. // Time the RDS was last updated. // Time the RDS was last called. // Status of the last RDS call, "success" or "failure." // Error message of the last RDS call, or blank.
// User defined label for the RDS. // RDS URL. |
Splunk Ping Body
|
{ "event": {<default ping body>}, "source": "orbital", "sourcetype": "_json" } |
RDS Payloads
Once the RDS is created, new scheduled jobs can be associated with an RDS so that results get sent to the RDS via an HTTP POST. The default result wrapper is described as well as the Splunk specific wrapper. Additionally, the result itself can use the compact or expanded formats, both described below.
Results Headers
|
{ "X-Orbital-Event": ["job-results"] "X-Orbital-Eventid": ["QiI8Tmnv2XTJak3myq5duw"], // Value is the ID of the Orbital live query or scheduled query for result set. "Accept-Encoding": ["gzip"], "User-Agent": ["Go-http-client/1.1"], "Content-Length": [1540], "Content-Type": ["application/json"] } |
Default Results Body
|
{ "job-results": [ <job-result 1>, <job-result 2>, <job-result N> ] } |
Splunk Results Body
|
{ "event": {<job result with selected format>}, "source": "orbital", "sourcetype": "_json" } |
The job-result Object
|
{ "version": 3, "format": "compact", "query": { "id": "0IXVxgIqx-KvHUGL9kHRug", "context": { "key": "val" } "osquery": [ { "types": [column. "crontab_event", "crontab_minute", "crontab_hour", "crontab_day_of_month", "crontab_month", "crontab_day_of_week", "command_line", "file_path" ], |
// Result notice protocol version. // Result format identifier. // Information about the query that spawned the results. // Orbital ID from the live query or scheduled query that spawned the results. // Map of key-value pairs provided to the query, if any.
// List of osquery sql stanzas and metadata.
// Observable type hint for each result |
|
"sql": "SELECT event, minute, hour, day_of_month, month, day_of_week, command, path \nFROM crontab;\n", // SQL statement |
|
|
"label": "crontab_monitoring", "name": "Crontab Events" } ] }, "results": [ <formatted result 1>, <formatted result 2>, <formatted result N> ] } |
// Custom unique identifier for this stanza of SQL. // Custom human readable name for this stanza of SQL.
// List of Orbital formatted results, either compact or expanded. |
Result Format
The formatted-result payload comes in two varieties, compact and expanded. They differ in their presentation of result rows and columns.
Compact Formatted Result
This is an example compact formatted result for the Orbital Catalog query Crontab Events.
|
{ "nodeinfo":{ "id":"aCaqXcztcZ4DDhPjsIGJkA", "ampuuid":"19504e9e-88a6-4ba7-a079-c24c6eb597d8", "os":"windows" }, "id": "Rv-BriP-XAMev3LN8DNoug", "creator": "7ef6da70-eeef-4a18-83ea-2e94dd6f9ba2", "organization": "d76c035d-e896-438c-8d75-158be85fc958", "endpoint_organization": "d76c035d-e896-438c-8d75-158be85fc958", "endpoint_type": "amp", "reported": "2020-09-15T21:03:38.067793669Z", "error": "", "node": "aCaqXcztcZ4DDhPjsIGJkA", "query": "0IXVxgIqx-KvHUGL9kHRug", "osQuery": [ { "types": [ "", "", "", "", "", "", "", "file_path" ], "columns": [ "event", "minute", "hour", "day_of_month", "month", "day_of_week", "command", "path" ], "values": [ "", "17", "*", "*", "*", "*", "root cd / && run-parts --report /etc/cron.hourly", "/etc/crontab", "", "25", "6", "*", "*", "*", |
// Orbital ID associated with the endpoint. // Secure Endpoint GUID associated with the endpoint. // OS of the endpoint.
// Orbital ID of this result. // User ID associated with this result. // Organization ID associated with the query that created the result. // Organization ID associated with the endpoint that created the result. // Endpoint type for the endpoint that created this result. // Time the result was reported from the endpoint. // Error reported from the endpoint, or empty. // Orbital ID associated with the endpoint. // Orbital ID from the query that spawned this result. // List of osquery result objects, one per input SQL stanza.
// Observable types for each result column, if any.
// Column names for results.
// Serialized data from all columns and rows for this SQL stanza. |
|
"root test -x /usr/sbin/anacron || ( cd / && run-parts --report |
|
|
/etc/cron.daily )", "/etc/crontab", "", "47", "6", "*", "*", "7", |
|
|
"root test -x /usr/sbin/anacron || ( cd / && run-parts --report |
|
|
/etc/cron.weekly )", "/etc/crontab", "", "52", "6", "1", "*", "*", |
|
|
"root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly )", |
|
|
"/etc/crontab" ],> "error": "", "secs": 0.0008076209924183786, "label": "crontab_monitoring", "name": "Crontab Events" } ], "resultsCompressed": false, "context": { "key": "val" } "hostinfo": { "osinfo": { "os": "windows", "osname": "", "release": "5.0.0-23-generic", "version": "#24~18.04.1-Ubuntu SMP Mon Jul 29 16:12:28 UTC 2019", "arch": "amd64" }, "hostname": "myP52", "fqdn": { "127.0.1.1": "myP52" }, "interfaces": { "br-3cb44620fa12": { "name": "br-3cb44620fa12", "mac": "02:42:34:92:b5:93", "ipv4": "172.18.0.1/16", "active": false }, "wlp0s20f3": { "name": "wlp0s20f3", "mac": "d4:3b:04:0c:36:c1", "ipv4": "10.99.154.69/28", "ipv6": "fe80::f24f:9302:5686:fa04/64", "active": false } }, "external": { "name": "", "mac": "", "ipv4": "127.0.0.1", "active": true }, "updated": "2020-09-15T19:08:29.362008182Z", "version": "" }, "rowcount": 4, "seconds": 0.0014323319774121046 |
// Error for this SQL stanza, if any. // Time in seconds to run this SQL stanza on the endpoint. // Custom input label associated with this SQL stanza. // Custom input name associated with this SQL stanza.
// Always false. // Map of key-value pairs provided to the query, if any.
// Host information for the endpoint. Note fieldname difference from expanded.
// Number of rows from all SQL stanzas combined. // Number of seconds to process all SQL stanzas combined. |
|
"source_uri": "https://orbital.amp.cisco.com/jobs/job-id/results" // Service link for result. |
|
| } | |
Expanded Formatted Result
This is an example expanded formatted result for the Orbital Catalog query Crontab Events.
|
{ "id": "cukgSCMixtO8G2KPmUKKJA", "creator": "7ef6da70-eeef-4a18-83ea-2e94dd6f9ba2", "organization": "d76c035d-e896-438c-8d75-158be85fc958", "endpoint_organization": "d76c035d-e896-438c-8d75-158be85fc958", "endpoint_type": "amp", "reported": "2020-09-15T20:49:26.896692372Z", "error": "", "nodeinfo":{ "id":"aCaqXcztcZ4DDhPjsIGJkA", "ampuuid":"19504e9e-88a6-4ba7-a079-c24c6eb597d8", "os":"windows" }, "query": "0IXVxgIqx-KvHUGL9kHRug", "osQuery": [ { "types":[ "", "", "", "", "", "", "", "file_path" ], "columns":[ "event", "minute", "hour", "day_of_month", "month", "day_of_week", "command", "path" ], "table":[ { "meta_name":"Crontab Events" "meta_label":"crontab_monitoring", "event":"", "minute":"17", "hour":"*", "day_of_month":"*", "month":"*", "day_of_week":"*", |
// Orbital ID of this result. // User ID associated with this result. // Organization ID associated with the query that created the result. // Organization ID associated with the endpoint that created the result. // Endpoint type for the endpoint that created this result. // Time the result was reported from the endpoint. // Error reported from the endpoint, or empty.
// Orbital ID associated with the endpoint. // Secure Endpoint GUID associated with the endpoint. // OS of the endpoint.
// Orbital ID from the query that spawned this result. // List of osquery result objects, one per input SQL stanza.
// Observable types for each result column, if any.
// Column names for results.
// Custom input name associated with this SQL stanza. // Custom input label associated with this SQL stanza. // Row data in key-value format, in column order. |
|
|
"command":"root cd / \u0026\u0026 run-parts --report /etc/cron.hourly", |
||
|
"path":"/etc/crontab" }, { "meta_name":"Crontab Events" "meta_label":"crontab_monitoring", "event":"", "minute":"25", "hour":"6", "day_of_month":"*", "month":"*", "day_of_week":"*", |
||
|
"command":"root test -x /usr/sbin/anacron || ( cd / \u0026\u0026 run-parts --report /etc/cron.daily )", |
||
|
"path":"/etc/crontab" }, { "meta_name":"Crontab Events" "meta_label":"crontab_monitoring", "event":"", "minute":"47", "hour":"6", "day_of_month":"*", "month":"*", "day_of_week":"7", |
||
|
"command":"root test -x /usr/sbin/anacron || ( cd / \u0026\u0026 run-parts --report /etc/cron.weekly )", |
||
|
"path":"/etc/crontab" }, { "meta_name":"Crontab Events" "meta_label":"crontab_monitoring", "event":"", "minute":"52", "hour":"6", "day_of_month":"1", "month":"*", "day_of_week":"*", |
||
|
"command":"root test -x /usr/sbin/anacron || ( cd / \u0026\u0026 run-parts --report /etc/cron.monthly )", |
||
|
"path":"/etc/crontab" } ], "error": "", "secs": 0.0008076209924183786, "label": "crontab_monitoring", "name": "Crontab Events" } ], "context": { "key": "val" } "info":{ "osinfo":{ "os":"windows", "osname":"", "release":"5.0.0-23-generic", |
// Error for this SQL stanza, if any. // Time in seconds to run this SQL stanza on the endpoint. // Custom input label associated with this SQL stanza. // Custom input name associated with this SQL stanza.
// Map of key-value pairs provided to the query, if any. // Host information for the endpoint. Note fieldname difference from compact |
|
|
"version":"#24~18.04.1-Ubuntu SMP Mon Jul 29 16:12:28 UTC 2019", |
||
|
"arch":"amd64" }, "hostname":"myP52", "fqdn":{ "127.0.1.1":"myP52" }, "interfaces":{ "br-3cb44620fa12":{ "name":"br-3cb44620fa12", "mac":"02:42:52:92:b5:93", "ipv4":"172.18.0.1/16", "active":false }, "wlp0s20f3":{ "name":"wlp0s20f3", "mac":"d4:3b:04:0c:82:c1", "ipv4":"10.99.154.69/28", "ipv6":"fe80::f24f:9302:5686:fa04/64", "active":false } }, "external":{ "name":"", "mac":"", "ipv4":"127.0.0.1", "active":true }, "updated":"2020-09-15T19:08:29.362008182Z", "version":"" }, "rowcount": 4, "seconds": 0.0014323319774121046 "source_uri": |
// Number of rows from all SQL stanzas combined. // Number of seconds to process all SQL stanzas combined. |
|
|
"https://orbital.amp.cisco.com/jobs/job-id/results" // Service link for result. |
||
| } | ||
| Note: | Orbital will not remove documented RDS result fields, but reserves the right to add fields to the output as they become necessary. |
| Note: | The compact field job-results.results.hostinfo is named job-results.results.info in the expanded format. |